.TH g_wham 1 "Thu 26 Aug 2010" "" "GROMACS suite, VERSION 4.5"
.SH NAME
g_wham - weighted histogram analysis after umbrella sampling

.B VERSION 4.5
.SH SYNOPSIS
\f3g_wham\fP
.BI "\-ix" " pullx\-files.dat "
.BI "\-if" " pullf\-files.dat "
.BI "\-it" " tpr\-files.dat "
.BI "\-ip" " pdo\-files.dat "
.BI "\-o" " profile.xvg "
.BI "\-hist" " histo.xvg "
.BI "\-bsres" " bsResult.xvg "
.BI "\-bsprof" " bsProfs.xvg "
.BI "\-tab" " umb\-pot.dat "
.BI "\-wcorr" " cycl\-corr.xvg "
.BI "\-[no]h" ""
.BI "\-[no]version" ""
.BI "\-nice" " int "
.BI "\-xvg" " enum "
.BI "\-min" " real "
.BI "\-max" " real "
.BI "\-[no]auto" ""
.BI "\-bins" " int "
.BI "\-temp" " real "
.BI "\-tol" " real "
.BI "\-[no]v" ""
.BI "\-b" " real "
.BI "\-e" " real "
.BI "\-dt" " real "
.BI "\-[no]histonly" ""
.BI "\-[no]boundsonly" ""
.BI "\-[no]log" ""
.BI "\-unit" " enum "
.BI "\-zprof0" " real "
.BI "\-cycl" " enum "
.BI "\-alpha" " real "
.BI "\-[no]flip" ""
.BI "\-[no]hist\-eq" ""
.BI "\-nBootstrap" " int "
.BI "\-bs\-dt" " real "
.BI "\-bs\-seed" " int "
.BI "\-[no]histbs" ""
.BI "\-histbs\-block" " int "
.BI "\-[no]vbs" ""
.SH DESCRIPTION
\&This is an analysis program that implements the Weighted
\&Histogram Analysis Method (WHAM). It is intended to analyze
\&output files generated by umbrella sampling simulations to 
\&compute a potential of mean force (PMF). 


\&At present, three input modes are supported:

\&\fB *\fR With option \fB \-it\fR, the user provides a file which contains the
\&  filenames of the umbrella simulation run\-input files (tpr files),
\&  AND, with option \-ix, a file which contains filenames of
\&  the pullx mdrun output files. The tpr and pullx files must
\&  be in corresponding order, i.e. the first tpr created the
\&  first pullx, etc.

\&\fB *\fR Same as the previous input mode, except that the the user
\&  provides the pull force ouput file names (pullf.xvg) with option \-if.
\&  From the pull force the position in the ubrella potential is
\&  computed. This does not work with tabulated umbrella potentials.
\&\fB *\fR With option \fB \-ip\fR, the user provides filenames of (gzipped) pdo files, i.e.
\&  the gromacs 3.3 umbrella output files. If you have some unusual
\&  reaction coordinate you may also generate your own pdo files and
\&  feed them with the \-ip option into to g_wham. The pdo file header
\&  must be similar to the folowing:

\&\fB  UMBRELLA      3.0

\& Component selection: 0 0 1

\& nSkip 1

\& Ref. Group 'TestAtom'

\& Nr. of pull groups 2

\& Group 1 'GR1'  Umb. Pos. 5.0 Umb. Cons. 1000.0

\& Group 2 'GR2'  Umb. Pos. 2.0 Umb. Cons. 500.0

\&\fR

\&  Nr of pull groups, umbrella positions, force constants, and names
\&  may (of course) differ. Following the header, a time column and
\&  a data columns for each pull group follow (i.e. the displacement
\&  with respect to the umbrella center). Up to four pull groups are possible
\&  at present.


\&By default, the output files are

\&  \fB \-o\fR      PMF output file

\&  \fB \-hist\fR   histograms output file


\&The umbrella potential is assumed to be harmonic and the force constants are 
\&read from the tpr or pdo files. If a non\-harmonic umbrella force was applied 
\&a tabulated potential can be provied with \-tab.


\&WHAM OPTIONS


\&  \fB \-bins\fR   Nr of bins used in analysis

\&  \fB \-temp\fR   Temperature in the simulations

\&  \fB \-tol\fR    Stop iteration if profile (probability) changed less than tolerance

\&  \fB \-auto\fR   Automatic determination of boudndaries

\&  \fB \-min,\-max\fR   Boundaries of the profile 

\&The data points which are used 
\&to compute the profile can be restricted with options \-b, \-e, and \-dt. 
\&Play particularly with \-b to ensure sufficient equilibration in each 
\&umbrella window!


\&With \-log (default) the profile is written in energy units, otherwise (\-nolog) as 
\&probability. The unit can be specified with \-unit. With energy output, 
\&the energy in the first bin is defined to be zero. If you want the free energy at a different 
\&position to be zero, choose with \-zprof0 (useful with bootstrapping, see below).


\&For cyclic (or periodic) reaction coordinates (dihedral angle, channel PMF
\&without osmotic gradient), \-cycl is useful.

\&\fB \-cycl yes\fR        min and max are assumed to
\&be neighboring points and histogram points outside min and max are mapped into 
\&the interval [min,max] (compare histogram output). 

\&\fB \-cycl weighted\fR   First, a non\-cyclic profile is computed. Subsequently, 
\&periodicity is enforced by adding corrections dG(i) between neighboring bins
\&i and i+1. The correction is chosen proportional to 1/[n(i)*n(i+1)]alpha, where
\&n(i) denotes the total nr of data points in bin i as collected from all histograms.
\&alpha is defined with \-alpha. The corrections are written to the file defined by \-wcorr.
\& (Compare Hub and de Groot, PNAS 105:1198 (2008))


\&ERROR ANALYSIS

\&Statistical errors may be estimated with bootstrap analysis. Use it with care, 
\&otherwise the statistical error may be substantially undererstimated !!

\&\fB \-nBootstrap\fR defines the nr of bootstraps. Two bootstrapping modes are supported.

\&\fB \-histbs\fR    Complete histograms are considered as independent data points (default). For each
\&bootstrap, N histograms are randomly chosen from the N given histograms (allowing duplication).
\&To avoid gaps without data along the reaction coordinate blocks of histograms (\-histbs\-block)
\&may be defined. In that case, the given histograms are divided into blocks and 
\&only histograms within each block are mixed. Note that the histograms
\&within each block must be representative for all possible histograms, otherwise the
\&statistical error is undererstimated!

\&\fB \-nohistbs\fR  The given histograms are used to generate new random histograms,
\&such that the generated data points are distributed according the given histograms. The number
\&of points generated for each bootstrap histogram can be controlled with \-bs\-dt.
\&Note that one data point should be generated for each *independent* point in the given
\&histograms. With the long autocorrelations in MD simulations, this procedure may 
\&easily understimate the error!

\&Bootstrapping output:

\&\fB \-bsres\fR   Average profile and standard deviations

\&\fB \-bsprof\fR  All bootstrapping profiles

\&With \fB \-vbs\fR (verbose bootstrapping), the histograms of each bootstrap are written, and, 
\&with \fB \-nohistBS\fR, the cummulants of the histogram.
.SH FILES
.BI "\-ix" " pullx\-files.dat" 
.B Input, Opt.
 Generic data file 

.BI "\-if" " pullf\-files.dat" 
.B Input, Opt.
 Generic data file 

.BI "\-it" " tpr\-files.dat" 
.B Input, Opt.
 Generic data file 

.BI "\-ip" " pdo\-files.dat" 
.B Input, Opt.
 Generic data file 

.BI "\-o" " profile.xvg" 
.B Output
 xvgr/xmgr file 

.BI "\-hist" " histo.xvg" 
.B Output
 xvgr/xmgr file 

.BI "\-bsres" " bsResult.xvg" 
.B Output, Opt.
 xvgr/xmgr file 

.BI "\-bsprof" " bsProfs.xvg" 
.B Output, Opt.
 xvgr/xmgr file 

.BI "\-tab" " umb\-pot.dat" 
.B Input, Opt.
 Generic data file 

.BI "\-wcorr" " cycl\-corr.xvg" 
.B Input, Opt.
 xvgr/xmgr file 

.SH OTHER OPTIONS
.BI "\-[no]h"  "no    "
 Print help info and quit

.BI "\-[no]version"  "no    "
 Print version info and quit

.BI "\-nice"  " int" " 19" 
 Set the nicelevel

.BI "\-xvg"  " enum" " xmgrace" 
 xvg plot formatting: \fB xmgrace\fR, \fB xmgr\fR or \fB none\fR

.BI "\-min"  " real" " 0     " 
 Minimum coordinate in profile

.BI "\-max"  " real" " 0     " 
 Maximum coordinate in profile

.BI "\-[no]auto"  "yes   "
 determine min and max automatically

.BI "\-bins"  " int" " 200" 
 Number of bins in profile

.BI "\-temp"  " real" " 298   " 
 Temperature

.BI "\-tol"  " real" " 1e\-06 " 
 Tolerance

.BI "\-[no]v"  "no    "
 verbose mode

.BI "\-b"  " real" " 50    " 
 first time to analyse (ps)

.BI "\-e"  " real" " 1e+20 " 
 last time to analyse (ps)

.BI "\-dt"  " real" " 0     " 
 Analyse only every dt ps

.BI "\-[no]histonly"  "no    "
 Write histograms and exit

.BI "\-[no]boundsonly"  "no    "
 Determine min and max and exit (with \-auto)

.BI "\-[no]log"  "yes   "
 Calculate the log of the profile before printing

.BI "\-unit"  " enum" " kJ" 
 energy unit in case of log output: \fB kJ\fR, \fB kCal\fR or \fB kT\fR

.BI "\-zprof0"  " real" " 0     " 
 Define profile to 0.0 at this position (with \-log)

.BI "\-cycl"  " enum" " no" 
 Create cyclic/periodic profile. Assumes min and max are the same point.: \fB no\fR, \fB yes\fR or \fB weighted\fR

.BI "\-alpha"  " real" " 2     " 
 for '\-cycl weighted', set parameter alpha

.BI "\-[no]flip"  "no    "
 Combine halves of profile (not supported)

.BI "\-[no]hist\-eq"  "no    "
 Enforce equal weight for all histograms. (Non\-Weighed\-HAM)

.BI "\-nBootstrap"  " int" " 0" 
 nr of bootstraps to estimate statistical uncertainty

.BI "\-bs\-dt"  " real" " 0     " 
 timestep for synthetic bootstrap histograms (ps). Ensure independent data points!

.BI "\-bs\-seed"  " int" " \-1" 
 seed for bootstrapping. (\-1 = use time)

.BI "\-[no]histbs"  "yes   "
 In bootstrapping, consider complete histograms as one data point. Accounts better for long autocorrelations.

.BI "\-histbs\-block"  " int" " 8" 
 when mixin histograms only mix within blocks of \-histBS_block.

.BI "\-[no]vbs"  "no    "
 verbose bootstrapping. Print the cummulants and a histogram file for each bootstrap.

.SH SEE ALSO
.BR gromacs(7)

More information about \fBGROMACS\fR is available at <\fIhttp://www.gromacs.org/\fR>.
